{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# OpenAI Responses API with Structured Output\n",
    "\n",
    "This example demonstrates how to use Structured Outputs with OpenAI's Responses API client.\n",
    "\n",
    "**Note: Current support for the OpenAI Responses API is limited to `initiate_chat` with a two-agent chat. Future releases will included expanded support for group chat and the `run` interfaces.**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Install AG2 and dependencies\n",
    "\n",
    "To be able to run this notebook, you will need to install AG2 with the `openai` extra.\n",
    "````{=mdx}\n",
    ":::info Requirements\n",
    "Install `ag2` with 'openai' extra:\n",
    "```bash\n",
    "pip install ag2[openai]\n",
    "```\n",
    "For more information, please refer to the [installation guide](https://docs.ag2.ai/latest/docs/user-guide/basic-concepts/installing-ag2).\n",
    ":::\n",
    "````"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "\n",
    "from pydantic import BaseModel\n",
    "\n",
    "from autogen import AssistantAgent, UserProxyAgent\n",
    "\n",
    "\n",
    "# ---------------------------------------------------------------------\n",
    "# 1. Define the response format (a Pydantic model)\n",
    "# ---------------------------------------------------------------------\n",
    "class QA(BaseModel):\n",
    "    question: str\n",
    "    answer: str\n",
    "    reasoning: str\n",
    "\n",
    "\n",
    "# ---------------------------------------------------------------------\n",
    "# 2. Build an llm_config that opts-in to the Responses endpoint\n",
    "#    and attaches the structured-output model\n",
    "# ---------------------------------------------------------------------\n",
    "llm_config = {\n",
    "    \"config_list\": [\n",
    "        {\n",
    "            \"api_type\": \"responses\",  # <─ use /responses\n",
    "            \"model\": \"gpt-4.1\",  # any supported model\n",
    "            \"api_key\": os.getenv(\"OPENAI_API_KEY\"),\n",
    "            \"response_format\": QA,  # <─ structured output!\n",
    "        }\n",
    "    ]\n",
    "}\n",
    "\n",
    "# ---------------------------------------------------------------------\n",
    "# 3. Create two simple chat actors\n",
    "# ---------------------------------------------------------------------\n",
    "user = UserProxyAgent(\n",
    "    name=\"User\",\n",
    "    system_message=\"Human admin\",\n",
    "    human_input_mode=\"NEVER\",\n",
    ")\n",
    "\n",
    "assistant = AssistantAgent(\n",
    "    name=\"StructuredBot\",\n",
    "    llm_config=llm_config,\n",
    "    system_message=(\n",
    "        \"You are a Q&A bot. Always return a JSON object that matches the QA schema: {question, answer, reasoning}\"\n",
    "    ),\n",
    ")\n",
    "\n",
    "# ---------------------------------------------------------------------\n",
    "# 4. Start the conversation\n",
    "# ---------------------------------------------------------------------\n",
    "result = user.initiate_chat(\n",
    "    assistant,\n",
    "    message=\"What causes seasons on Earth?\",\n",
    "    max_turns=1,\n",
    "    summary_method=\"last_msg\",\n",
    ")\n",
    "\n",
    "# ---------------------------------------------------------------------\n",
    "# 5. Parse and print the result\n",
    "# ---------------------------------------------------------------------\n",
    "try:\n",
    "    qa = QA.model_validate_json(result.summary)\n",
    "    print(f\"Question: {qa.question}\")\n",
    "    print(f\"Answer: {qa.answer}\")\n",
    "    print(f\"Reasoning: {qa.reasoning}\")\n",
    "except Exception as e:\n",
    "    print(f\"Error parsing result: {e}\")"
   ]
  }
 ],
 "metadata": {
  "front_matter": {
   "description": "This example demonstrates how to use Structured Output with OpenAI response API client.",
   "tags": [
    "structured output",
    "responses",
    "code generation",
    "debugging"
   ]
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
